Security Guide

Using Web Services Policy to Specify Inbound Message-Level Security

To express the inbound message-level security requirements for a proxy service or business service that is a Web service, you use the Web Services Policy (WS-Policy) framework. The following sections describe configuring WS-Policy for proxy services and business services:

About Web Services Policy

Web Services Policy (WS-Policy) is a standards-based framework for defining a Web service’s security constraints and requirements. It expresses security constraints and requirements in a collection of XML statements called policies, each of which contains one or more assertions.

In AquaLogic Service Bus, WS-Policy assertions are used to specify a Web service’s requirements for digital signatures and encryption, along with the security algorithms and authentication mechanisms that it requires.

Because the WS-Policy specification has not been fully standardized, AquaLogic Service Bus supports a WebLogic Server-proprietary format that is based on the assertions described in the December 18, 2002 version of the Web Services Security Policy Language (WS-SecurityPolicy) specification. This release of AquaLogic Service Bus does not incorporate the latest update of the specification (13 July 2005). While the WS-Policy specification defines both security and reliable messaging assertions, AquaLogic Service Bus supports only security assertions. The syntax and usage of AquaLogic Service Bus security assertions differ from the WS-Policy specification, but the assertions are similar in meaning and are fully compatible with security assertions used in WebLogic Server 9.0 and 9.1 Web services.

WS-Policy policies may be included directly in a WSDL document or included by reference, and a WSDL document may import other WSDL documents that contain or refer to WS-Policy policies. An XML file that contains these policies can be used by multiple proxy services or business services.

Abstract and Concrete WS-Policy Statements

The WebLogic Web Services runtime environment recognizes two types of WS-Policy statements:

Concrete WS-Policy statements specify the security tokens that are used for authentication, encryption, and digital signatures.

You can create concrete WS-Policy statements if you know at design time the type of authentication (such as using X.509 or SAML tokens) that you want to require; whether multiple private key and certificate pairs from the keystore are going to be used for encryption and digital signatures; and so on.

Abstract WS-Policy statements do not specify security tokens. Specifically, this means the <Identity> and <Integrity> elements (or assertions) of the WS-Policy files do not contain a <SupportedTokens><SecurityToken> child element, and the <Confidentiality> element WS-Policy file does not contain a <KeyInfo><SecurityToken> child element.

The AquaLogic Service Bus runtime environment determines which security token types an abstract policy will accept. For information on configuring the runtime environment to accept specify types of tokens, see step 3 in Configuring Inbound Message-Level Security.

AquaLogic Service Bus WS-Policy Statements

AquaLogic Service Bus includes three XML files that contain simple, abstract WS-Policy policies:

Auth.xml—contains a policy that requires Web service clients to authenticate.
Encrypt.xml—contains a policy that requires clients to encrypt the SOAP body with 3DES-CBC. The key wrapping algorithm is RSA 1.5. A symmetric key for Triple DES (Data Encryption Standard) is generated by the client and encrypted for the recipient with RSA 1.5.

You cannot use this policy with a business service. Instead, create your own concrete encryption policy. See Creating and Using Custom WS-Policy Statements.

Sign.xml—contains a policy that requires clients to sign the SOAP body. It also requires that the WS-Security engine on the client add a signed timestamp to the wsse:Security header—which prevents certain replay attacks. All system headers are also signed. The digital signature algorithm is RSA-SHA1. Exclusive XML canonicalization is used.

The system headers are:

wsrm:SequenceAcknowledgement
wsrm:AckRequested
wsrm:Sequence
wsa:Action
wsa:From
wsa:To
wsa:FaultTo
wsa:MessageID
wsa:RelatesTo
wsa:ReplyTo
wsu:Timestamp
wsax:SetCookie

The name space prefixes correspond to the name spaces in the following table:

Prefix	Name Space
`wsrm`	`http://schemas.xmlsoap.org/ws/2005/02/rm`
`wsa`	`http://schemas.xmlsoap.org/ws/2004/08/addressing`
`wsu`	`http://schemas.xmlsoap.org/ws/2002/07/utility`
`wsax`	`http://schemas.xmlsoap.org/ws/2004/01/addressingx`

The AquaLogic Service Bus policy files are the same policy files that WebLogic Server provides. To see contents of these XML files, see “WebLogic Server WS-Policy Files” in Configuring Security in Programming Web Services for WebLogic Server.

BEA recommends that you use these pre-packaged policies whenever possible. However, you can not use them under the following conditions:

If you need to specify that particular parts of the body of a SOAP message are encrypted or digitally signed, rather than the entire body, you cannot use the AquaLogic Service Bus WS-Policy statements. Instead, create custom WS-Policy statements. See Example: Encrypting Part of the SOAP Body and Header.
If you require clients to provide SAML tokens, you cannot use the AquaLogic Service Bus WS-Policy statements. WS-Policy statements that require SAML tokens must specify the confirmationMethod and therefore must be concrete.
If you want a business service to require digital encryption, you cannot use the AquaLogic Service Bus WS-Policy encryption statement. Business services require concrete encryption policies (the certificate must be embedded in the policy).

For information on using these policies in your proxy services or business services, see Attaching WS-Policy Statements to WSDL Documents.

Creating and Using Custom WS-Policy Statements

If the AquaLogic Service Bus WS-Policy statements do not meet your security needs, you can write your own WS-Policy statements (custom WS-Policy statements). You cannot modify the AquaLogic Service Bus WS-Policy statements.

You can either write custom WS-Policy statements directly in your Web service’s WSDL document or, if you want to reuse your statements in multiple Web services, write them in a separate XML file, import them to AquaLogic Service Bus, and refer to them from the WSDL documents.

Note the following restrictions for WS-Policy statements in AquaLogic Service Bus:

While the WS-Policy specification allows WS-Policy statements to include both security and reliable messaging assertions, AquaLogic Service Bus supports only security assertions.
In AquaLogic Service Bus, WS-Policies are required to have an Id attribute from the following name space:
http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd

The value of this attribute must be unique across all WS-Policy statements in the AquaLogic Service Bus domain. This attribute is optional in the WS-Policy schema but required in an AquaLogic Service Bus Web service.

If you create a confidentiality assertion in a proxy service, it must be abstract (the certificate must not be embedded in the policy). You will get error messages while creating a proxy service that contains a concrete confidentiality assertion.
If you create a confidentiality assertion in a business service, it must be concrete (the certificate must be embedded in the policy) and it must be located directly in the WSDL document. You cannot attach such a policy by reference. See Example: Encryption Policy for a Business Service.

Examples of Custom WS-Policy Statements

The following sections provide examples of custom WS-Policy statements:

Example: Encrypting Part of the SOAP Body and Header

If you need to specify that particular parts of the body of a SOAP message are encrypted or digitally signed, rather than the entire body, you must create a custom WS-Policy file.

Listing 7-1 is an abstract WS-Policy statement that does the following:

Requires the message from the client to include a user name and password token for authentication
Requires the client to encrypt the user name token (which is in the security header)
Requires the client to encrypt the /definitions/message/CreditCardNumber element

This policy cannot be used with a business service because it is abstract: its KeyInfo element does not contain the certificate used for encryption. Instead, when you activate a proxy service that uses this WS-Policy statement, AquaLogic Service Bus binds to the WS-Policy statement the encryption certificate from the proxy service provider that you associate with the proxy service. See Proxy Service Providers in Using the AquaLogic Service Bus Console.

Figure 7-1 Binding a Certificate to an Abstract Policy

Also in Listing 7-1:

The KeyWrappingAlgorithm element specifies that the client must use the RSA 1.5 algorithm to wrap symmetric keys.
The EncryptionAlgorithm specifies that the client must use the Triple DES (Data Encryption Standard) algorithm perform encrypt the security header and message body.

Listing 7-1 Encrypting Part of the SOAP Body and Header

<wsp:Policy
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wssp="http://www.bea.com/wls90/security/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
     wssecurity-utility-1.0.xsd"
   xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
     wssecurity-secext-1.0.xsd"
   xmlns:m="http://example.org"
   wsu:Id="encrypt-custom-body-element-and-username-token">

    <!-- Require messages to provide a user name and password token 
         for authentication --> 
   <wssp:Identity>
      <wssp:SupportedTokens>
        <wssp:SecurityToken IncludeInMessage="true"
            TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
               wss-username-token-profile-1.0#UsernameToken">
            <wssp:UsePassword Type="http://docs.oasis-open.org/wss/2004/01/
                oasis-200401-wss-username-token-profile-1.0#PasswordText"/>
        </wssp:SecurityToken>
      </wssp:SupportedTokens>
   </wssp:Identity>

   <wssp:Confidentiality>
      <wssp:KeyWrappingAlgorithm
        URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

      <!-- Require the user name and password in the security header
           to be encrypted --> 
      <wssp:Target>
        <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
        <wssp:MessageParts
          Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
          wls:SecurityHeader(wsse:UsernameToken)
        </wssp:MessageParts>
      </wssp:Target>

      <!-- Require the /definitions/message/CreditCardNumber element to 
           be encrypted --> 
      <wssp:Target>
        <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
        <wssp:MessageParts>
          wsp:GetBody(.)/m:CreditCardNumber
        </wssp:MessageParts>
      </wssp:Target>

      <!-- This is an abstract policy because the KeyInfo element is
          empty. The KeyInfo data is bound to the policy at runtime --> 
      <wssp:KeyInfo/>
   </wssp:Confidentiality>
</wsp:Policy>

Example: Encryption Policy for a Business Service

If you want messages to a business service to be encrypted, you must create a custom WS-Policy. The policy must be concrete (it must contain the encryption certificate instead of using a certificate from a proxy service provider) and it must be located directly in a WSDL document instead of being included by reference.

Typically, you would require messages to a business service to be encrypted if the proxy service that sends messages to the business service is a pass-through proxy service. That is, the proxy service that receives messages from a client does not process the SOAP message. Instead, the proxy service routes the message to the business service, and the business service takes on the responsibility of Web Services Security. See Configuring Inbound Message-Level Security.

Listing 7-2 is a WSDL document that contains a concrete policy. Note the following about this example:

The policy requires clients to encrypt the message body.
The KeyInfo element specifies the type of token that a client must provide to is the parent element that is used to describe and embed the encryption certificate. The BinarySecurityToken element contains the base-64 encoded encryption certificate (the value is truncated in the example). If your certificate is in PEM format, the content of the PEM file (without the PEM prefix and suffix) is the base-64 encoded representation of the certificate. If your encryption certificate is stored in a JDK keystore, you can easily export it to a PEM file.
The policy provides a unique ID and the WSDL uses a URI fragment to refer to the ID. See Attaching WS-Policy Statements to WSDL Documents.

Listing 7-2 Encrypting the Body with a Concrete Policy, Embedding the Policy in the WSDL Document

<definitions name="WssServiceDefinitions"
  targetNamespace="http://com.bea.alsb/tests/wss"
  xmlns="http://schemas.xmlsoap.org/wsdl/"
  xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
    wssecurity-utility-1.0.xsd"
  xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
  ...>

  <wsp:UsingPolicy xmlns:n1="http://schemas.xmlsoap.org/wsdl/"
      n1:Required="true"/>

  <!-- The policy provides a unique ID -->
  <wsp:Policy wsu:Id="myEncrypt.xml">
    <wssp:Confidentiality
        xmlns:wssp="http://www.bea.com/wls90/security/policy">
    <wssp:KeyWrappingAlgorithm
        URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

    <!-- Require the user name and password in the security header
         to be encrypted --> 
    <wssp:Target>
      <wssp:EncryptionAlgorithm
         URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
      <wssp:MessageParts          Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
         wsp:Body()
      </wssp:MessageParts>
    </wssp:Target>

      <!-- Embed the token type and encryption certificate --> 
      <wssp:KeyInfo>
        <wssp:SecurityToken 
            TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
               wss-x509-token-profile-1.0#X509v3"/>
        <wssp:SecurityTokenReference>
          <wssp:Embedded>
            <wsse:BinarySecurityToken
                EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-
                   200401-wss-soap-message-security-1.0#Base64Binary"
                ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-
                   200401-wss-x509-token-profile-1.0#X509v3"
                 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-
                   200401-wss-wssecurity-secext-1.0.xsd">
                 MIICfjCCAeegAwIBAgIQV/PDyj3...
            </wsse:BinarySecurityToken>
          </wssp:Embedded>
        </wssp:SecurityTokenReference>
      </wssp:KeyInfo>
    </wssp:Confidentiality>
  </wsp:Policy>

  <binding name="WssServiceSoapBinding" type="tns:WssService">
    <soap:binding style="document"
        transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="getPurchaseOrder">
      <soap:operation soapAction="" style="document"/>
      <input>
        <soap:body parts="parameters" use="literal"/>

        <!-- Use a URI fragment to refer to the unique policy ID -->
        <wsp:Policy>
          <wsp:PolicyReference URI="#myEncrypt.xml"/>
        </wsp:Policy>
      </input>
      <output>
          <soap:body parts="parameters" use="literal"/>
        </output>
      </operation>
    </binding>
    ...
</definitions>

Example: Encrypting a Custom SOAP Header

Listing 7-3 is an abstract WS-Policy statement that encrypts a custom header named CreditCardNumber.

Listing 7-3 Encrypting a Custom SOAP Header

<wsp:Policy
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wssp="http://www.bea.com/wls90/security/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
     wssecurity-utility-1.0.xsd"
   wsu:Id="dig-sig-for-get-header">
   <wssp:Confidentiality>
     <wssp:KeyWrappingAlgorithm
       URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

     <!-- Require the custom CreditCardNumber header to be encrypted --> 
     <wssp:Target>
        <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
        <wssp:MessageParts
           Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116">
           wsp:GetHeader(.)/n:CreditCardNumber
         </wssp:MessageParts>
     </wssp:Target>
     <wssp:KeyInfo/>
  </wssp:Confidentiality>
</wsp:Policy>

Example: Signing the Message Body and Headers

Listing 7-4 is a WS-Policy statement that requires a digital signature to access the following in the SOAP message:

A custom header named header1
All system headers
The message body

Listing 7-4 Requiring a Signature for SOAP Headers and Body

<wsp:Policy
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wssp="http://www.bea.com/wls90/security/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
   wssecurity-utility-1.0.xsd"
   wsu:Id="sign-custom-header-policy">

   <wssp:Integrity>
     <wssp:SignatureAlgorithm
       URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
     <wssp:CanonicalizationAlgorithm
       URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>

     <!-- Require the custom header header1 to be signed --> 
     <wssp:Target>
       <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
       <wssp:MessageParts
         Dialect="http://www.w3.org/TR/1999/REC-xpath-19991116"
         xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
           wssecurity-secext-1.0.xsd"
         xmlns:n="http://example.org">
         wsp:GetHeader(.)/n:header1
       </wssp:MessageParts>
     </wssp:Target>

     <!-- Require the system headers to be signed --> 
     <wssp:Target>
        <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
           <wssp:MessageParts
              Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
              wls:SystemHeaders()
           </wssp:MessageParts>
     </wssp:Target>

     <!-- Require the Timestamp header to be signed --> 
     <wssp:Target>
        <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <wssp:MessageParts
          Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
          wls:SecurityHeader(wsu:Timestamp)
        </wssp:MessageParts>
     </wssp:Target>

     <!-- Require the message body to be signed --> 
     <wssp:Target>
       <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
       <wssp:MessageParts
         Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
         wsp:Body()
       </wssp:MessageParts>
    </wssp:Target>
  </wssp:Integrity>
<wssp:MessageAge/>
</wsp:Policy>

Example: Signing a SOAP Body with SAML Holder-of-Key

Listing 7-5 is a WS-Policy statement that requires the SAML asserter to use the holder-of-key method to sign the message body. For information about the SAML holder-of-key method, see Web Services Security SAML Token Profile 1.0, at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf.

Listing 7-5 Signing a SOAP Body with SAML Holder-of-Key Method

<wsp:Policy
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wssp="http://www.bea.com/wls90/security/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
     wssecurity-utility-1.0.xsd"
   xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
   wsu:Id="saml-holder-of-key-signed">

  <wssp:Integrity>
     <wssp:SignatureAlgorithm
      URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
     <wssp:CanonicalizationAlgorithm
      URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>

     <wssp:Target>
       <wssp:DigestAlgorithm URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
       <wssp:MessageParts
         Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
         wsp:Body()
       </wssp:MessageParts>
     </wssp:Target>

     <wssp:SupportedTokens>
       <wssp:SecurityToken IncludeInMessage="true"
         TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-saml-
         token-profile-1.0#SAMLAssertionID">
         <wssp:Claims>
          <wssp:ConfirmationMethod>holder-of-key</wssp:ConfirmationMethod>
         </wssp:Claims>
       </wssp:SecurityToken>
     </wssp:SupportedTokens>

   </wssp:Integrity>
</wsp:Policy>

Example: Authenticating, Signing, and Encrypting a SOAP Body with SAML Sender Vouches

Listing 7-5 is a WS-Policy statement that requires the SAML asserter to use the sender-vouches method to sign the message body and headers. For information about the SAML sender-vouches method, see Web Services Security SAML Token Profile 1.0, at http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf.

Listing 7-6 Signing a SOAP Body with SAML Sender-Vouches Method

<wsp:Policy
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wssp="http://www.bea.com/wls90/security/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
     wssecurity-utility-1.0.xsd"
   xmlns:wls="http://www.bea.com/wls90/security/policy/wsee#part"
   wsu:Id="samlPolicy-sender-vouches-signed-encrypted">

   <wssp:Identity>
     <wssp:SupportedTokens>
       <wssp:SecurityToken
         TokenType="http://docs.oasis-open.org/wss/2004/01/oasis-2004-01-
           saml-token-profile-1.0#SAMLAssertionID">
          <wssp:Claims>
            <wssp:ConfirmationMethod>
               sender-vouches
            </wssp:ConfirmationMethod>
          </wssp:Claims>
       </wssp:SecurityToken>
     </wssp:SupportedTokens>
   </wssp:Identity>

   <wssp:Integrity>
     <wssp:SignatureAlgorithm
        URI="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
     <wssp:CanonicalizationAlgorithm
        URI="http://www.w3.org/2001/10/xml-exc-c14n#"/>

     <wssp:Target>
        <wssp:DigestAlgorithm
          URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <wssp:MessageParts
          Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
          wsp:Body()
        </wssp:MessageParts>
     </wssp:Target>

     <wssp:Target>
         <wssp:DigestAlgorithm
            URI="http://www.w3.org/2000/09/xmldsig#sha1"/>
         <wssp:MessageParts
             Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
             wls:SecurityHeader(Assertion)
         </wssp:MessageParts>
       </wssp:Target>
   </wssp:Integrity>

   <wssp:Confidentiality>
      <wssp:KeyWrappingAlgorithm
        URI="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

     <wssp:Target>
         <wssp:EncryptionAlgorithm
           URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
         <wssp:MessageParts
            Dialect="http://www.bea.com/wls90/security/policy/wsee#part">
            wls:SecurityHeader(Assertion)
         </wssp:MessageParts>
     </wssp:Target>

     <wssp:Target>
        <wssp:EncryptionAlgorithm
          URI="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
        <wssp:MessageParts
           Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part">
           wsp:Body()
        </wssp:MessageParts>
     </wssp:Target>

     <wssp:KeyInfo/>
   </wssp:Confidentiality>

</wsp:Policy>

Attaching WS-Policy Statements to WSDL Documents

AquaLogic Service Bus implements the WS-Policy Attachment specification ( http://www.w3.org/Submission/WS-PolicyAttachment/), which defines the mechanisms for associating WS-Policy statements with Web services.

To attach WS-Policy statements to a WSDL document for a Web service:

If you created a custom WS-Policy in a separate XML file, add the custom WS-Policy file as a resource in the AquaLogic Service Bus domain. See “Adding a Custom WS-Policy” under Custom WS-Policies in Using the AquaLogic Service Bus Console.
In the <definitions> element of the WSDL document, add the following child element:
<wsp:UsingPolicy wsdl:Required="true" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/>

The wsdl:required="true" attribute ensures that proxy services and business services are capable of processing the policy attachments.

If you do not add this element, AquaLogic Service Bus ignores any WS-Policy statements in the WSDL.

Within each element in the WSDL document that you want to secure:

Determine the URI of the WS-Policy statements that you want to use. See Determining the URI of a WS-Policy Statement.
Specify the URI in the WSDL document. See Specifying the URI of a WS-Policy Statement in a WSDL Document.

Determining the URI of a WS-Policy Statement

For the AquaLogic Service Bus WS-Policy statements, the URIs are always as follows:

policy:Auth.xml
policy:Encrypt.xml
policy:Sign.xml

For WS-Policy statements that are located directly in the WSDL document, the URI is as follows:
#policy-ID
where policy-ID is the value of the policy’s wsu:ID attribute. See Listing 7-8.

For WS-Policy statements that you created in a separate XML file and added as resources to AquaLogic Service Bus, the URI is as follows:
policy:policy-ID
where policy-ID is the value of the policy’s wsu:ID attribute (which you specified in the policy’s XML file).

You can also use UDDI to attach WS-Policy statements to a WSDL document, in which case the URI is expressed differently. For more information, see the WS-Policy Attachment specification ( http://www.w3.org/Submission/WS-PolicyAttachment/).

Specifying the URI of a WS-Policy Statement in a WSDL Document

Use one of the following techniques to specify the URI in a WSDL document:

PolicyURIs attribute

If the WSDL schema (described in http://www.w3.org/TR/wsdl) allows attribute extensibility for the element that you want secure, add the PolicyURIs global attribute to the element.

For the value of this element, specify a list of URIs, each of which refers to a single policy.

For example:
<input message="tns:foo" wsp:PolicyURIs="policy:Sign.xml"/>

Nested <Policy> element

If the WSDL schema allows element extensibility for the element that you want to secure, add <Policy> as a global child element. For each WS-Policy that you want to use, add one <PolicyReference> element as a child of the <Policy> element.

For each <PolicyReference> element, include a URI attribute that refers to a single policy. You can also include a digest and digest algorithm in the element.

For example:
<wsp:Policy> <wsp:PolicyReference URI="policy:Sign.xml"/> </wsp:Policy>

Table 7-1 lists the XPath name of WSDL elements and the technique that you use to specify the URI of the WS-Policy statement. The table also indicates the WSDL elements for which AquaLogic Service Bus does not support the attachment of WS-Policy statements.

Table 7-1 WSDL Elements That Can Be Protected in AquaLogic Service Bus
To Attach a Policy to This WSDL Element...	Use This Technique...
`/definitions/message`	Nested `<Policy>` element
`/definitions/message/part`	`PolicyURIs` attribute
`/definitions/portType`	`PolicyURIs` attribute
`/definitions/portType/operation`	Nested `<Policy>` element
`/definitions/portType/operation/input`	`PolicyURIs` attribute
`/definitions/portType/operation/output`	`PolicyURIs` attribute
`/definitions/portType/operation/fault`	AquaLogic Service Bus does not support attaching WS-Policy statements to this element
`/definitions/binding`	Nested `<Policy>` element
`/definitions/binding/operation`	Nested `<Policy>` element
`/definitions/binding/operation/input`	Nested `<Policy>` element
`/definitions/binding/operation/output`	Nested `<Policy>` element
`/definitions/binding/operation/fault`	AquaLogic Service Bus does not support attaching WS-Policy statements to this element
`/definitions/binding/service`	AquaLogic Service Bus does not support attaching WS-Policy statements to this element
`/definitions/service/port`	Nested `<Policy>` element

Best Practices: Attaching WS-Policy Statements

BEA recommends that you attach WS-Policy statements to any of the following elements or its descendants:

portType
binding

BEA recommends that you do not attach WS-Policy statements to the following elements:

service
port
message or message/part

Example: Requiring X.509 Credentials for Identity and Confidentiality

If a WS-Policy statement requires an X.509 token for authentication, it must also require a digital signature. An X.509 token cannot satisfy an identity assertion unless the client also signs some content with the corresponding private key.

To create a proxy service that requires clients to use X.509 certificates for authentication and digital signatures, you can do the following:

In the WSDL document that you will use to create a proxy service, attach the AquaLogic Service Bus policies that are in the Sign.xml and Auth.xml files. See Listing 7-7.
Configure the proxy service to use a proxy service provider that contains an X.509 certificate for digital signatures. See Proxy Service Providers in Using the AquaLogic Service Bus Console.

Because the AquaLogic Service Bus Sign.xml and Auth.xml policies are abstract, they will require the client to provide the credentials that are specified in the proxy service provider that is associated with the proxy service.

Listing 7-7 shows a WSDL with references to the AquaLogic Service Bus Sign.xml and Auth.xml policies.

Listing 7-7 WSDL with Policy References to AquaLogic Service Bus WS-Policies

<definitions
   ...
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401
      -wss-wssecurity-utility-1.0.xsd">

   <wsp:UsingPolicy
      wsdl:Required="true"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/>

...

   <portType name="Sample">
      <operation name="doFoo" parameterOrder="data">
         <input message="tns:foo" wsp:PolicyURIs="policy:Sign.xml"/>
         <output message="tns:fooResponse"/>
      </operation>
   </portType>

   <binding name="SampleBinding" type="tns:Sample">
      <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="doFoo">
         <wsp:Policy>
            <wsp:PolicyReference URI="policy:Sign.xml"/>
            <wsp:PolicyReference URI="policy:Auth.xml"/>
         </wsp:Policy>
         ...
      </operation>
      </binding>

...

</definitions>

Example: Attaching Custom Inline WS-Policy Statements to a WSDL Document

Listing 7-8 shows a WSDL with two custom WS-Policy policies, wsu:Id="policy1" and wsu:Id="policy2". The policies are located in the WSDL document; therefore the URIs that refer to these polices use XML fragments.

Listing 7-8 WSDL with Policy References to a Custom Inline Policy

<definitions
   ...
   xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-
   200401-wss-wssecurity-utility-1.0.xsd">

   <wsp:UsingPolicy
      wsdl:Required="true"
      xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"/>

<wsp:Policy wsu:Id="policy1">...</wsp:Policy>
<wsp:Policy wsu:Id="policy2">...</wsp:Policy>
...
   <portType name="Sample">
      <operation name="doFoo" parameterOrder="data">
         <input message="tns:foo" wsp:PolicyURIs="#policy1"/> 
         <output message="tns:fooResponse"/>
      </operation>
   </portType>

   <binding name="SampleBinding" type="tns:Sample">
      <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="doFoo">
         <wsp:Policy>
            <wsp:PolicyReference URI="#policy2"/>
         </wsp:Policy>
         <soap:operation
            soapAction="http://com.bea.samples/sample/doFoo"
            style="document"/>
         <input>
            <soap:body namespace="http://com.bea.samples/sample"
               use="literal"/>
         </input>
         <output>
            <soap:body namespace="http://com.bea.samples/sample"
              use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>

Policy Subjects and Effective Policy

A policy subject is an entity, such as service, endpoint, operation, or message, with which a policy can be associated. You can associate a single WS-Policy statement with multiple policy subjects; conversely, multiple WS-Policy statements can be associated with a single policy subject. A policy scope is the collection of policy subjects to which a policy applies. For example, the policy scope implied by a policy attached to wsd:binding/wsdl:operation/wsdl:input is the input message, the operation, the endpoint, and the service.

The effective policy for a given policy subject is the merge of all policies whose scopes contain that policy subject. For example, the effective policy of the input message of a binding operation is the merge of all policies attached to the following:

The input message of the binding operation
The binding operation
The binding
The input message of the port-type operation
The port-type operation
The port-type
The service

The AquaLogic Service Bus Console displays the effective policy (read only) when configuring a business or proxy service with WS-Policy statements, as shown in the following figure.

Figure 7-2 Effective Policy